-
Notifications
You must be signed in to change notification settings - Fork 175
Behavioural Database
HOME > SETUP > BEHAVIOURAL DATABASE
- Instrument Builder
- Scoring algorithms
- Populate test_names and test_subgroups tables
- Populate test_battery table
- Populate Examiners table
- Testing and Troubleshooting Instruments
- Double Data Entry
- Excluding Instruments
- Instrument Permissions
- Instrument Manager
This page covers how to create and install simple linst instrument forms in LORIS. For PHP forms, please refer to the Developer's Instrument Guide.
The Behavioural Database is the part of LORIS that implements the battery of tests and questionnaires which are administered and used to collect data on participants in a given study. These behavioural, psychological, and clinical tests are known as instruments or instrument forms.
Instrument forms fall into three categories: basic forms, forms with scoring algorithms, and forms populated by uploading data.
The battery is a list of which instruments are to be administered on each cohort of participants, and typically varies per timepoint and per study site. For example, the battery of instruments administered at a participant's first visit (e.g. timepoint V01) may depend on which cohort and study site they belong to. A participant may be tested on a certain set of instruments if they are in cohort A and from site X, but would be tested on different instruments if they are registered in cohort B at site Y.
Instruments commonly rate the severity of the symptoms they test through scoring functions.
The Instrument Builder (Tools menu) enables admin-level users to create simple instrument forms through the LORIS front-end. If your instrument contains one of the following, please follow the Developer's Instrument Guide for complex forms:
- Dependencies or rules between fields
Please note the Instrument Builder works best with Chrome or Firefox. (Safari and Explorer not recommended.)
- To start a new form, click the Build tab
- To upload and resume work on a previously created form, click the Load tab
For each field, select a type, provide the Question Name (e.g. handedness_q01_writing), Question Text (e.g Which hand is used for writing?), and other elements as required. Usable data types include:
Field Type | Description
--- | ---
Header | Specifies page title or section header. Text appears boldface at page centre. Note: Instrument Name automatically becomes the header at the top of form.
Label | Functions as a subtitle to introduce a subset of questions
Score Field | Specifies data entry fields. Scored field type must be indicated in "data entry" section.
Textbox | Used for fields with free text, preferably short answers
Textarea | Used for free text fields with longer inputs such as general comments, etc.
Dropdown | 'Dropdown option' row appears where option set entered. Once completed, click 'add row'. To create new dropdown menu, click 'reset'. 'not_answered' automatically added
Multiselect | Used for fields that have a select box where multiple options can be chosen.
Date | Used for creating a date field such as Date of Birth. Note: Date of Administration is automatically added at the top of form.
Numeric | Used for creating a numeric field such as Height, Weight, etc.
Blank Line | "Question Name" and "Question Text" can be left blank to separate page sections.
Page Break | Used to add a new page. "Question Text" can be the name of the new page.
- Do not use apostrophes (') or quotation marks in any field. Additionally Field Names should never include a space.
- Instrument Name, Date of Administration, and Age at administration will be added automatically at the top of the instrument form.
- Question Name must be unique, brief (shorter than 64 characters) and lowercase with no spaces (e.g. primary_language); this value becomes the MySQL field name in the instrument table (Database Name (DB). Question names should not end in "_status", as this is reserved for select boxes accompanying text fields.
- Question Text describes the item for data entry purposes, and often reflects the source questionnaire directly (e.g. "What is the child’s primary language?")
Click the Add Row button once all field information has been completed. In the preview panel underneath, click to edit any Question Name (in column Database Name (DB)).
Click on the Save tab to Validate, then Save to complete your instrument, which will download the $TESTNAME.linst file to your computer.
> Note: scripts may generate PHP Notice messages, which is normal and should not affect output.
Copy the downloaded $TESTNAME.linst file from your local machine into /var/www/loris/project/instruments/ on the LORIS server, and ensure the file is apache-readable (e.g. chmod a+r).
Then generate its MySQL table schema file ($TESTNAME.sql) by running the following php script:
cd /var/www/loris/tools
cat ../project/instruments/$TESTNAME.linst | php generate_tables_sql_and_testNames.phpIn MySQL, source the *.sql (or *.super_sql) file that was generated above:
> source ../project/tables_sql/$TESTNAME.sqlIf you get an error message "CREATE command denied", you have logged into MySQL as a user (e.g. lorisuser) with an insufficient privileges to administer this database. Switch to your admin-level credential (see #8 Install Script Inputs).
NOTE: Instrument files (*.linst, *sql) should be committed to a project-specific git repository.
In case of any changes to instrument field types, number of fields (add or delete), or field names, repeat steps above, keeping a safe copy of the original *.sql file, then run tools/generate_tables_sql.php instead of the php script run in step (ii).
Caveat: sourcing the *.sql file output by this script will delete all previously entered data for this instrument. To avoid losing data, we recommend instead diffing the original *.sql file against the new file, and using MySQL "alter table" statements to implement the specific instrument field changes.
If your instrument battery has been modified, please also see Re-populating instrument forms after battery changes
If an instrument form should include a scoring algorithm, a scoring script can be coded manually to accompany the form. This scoring script will be executed by Loris automatically when a user saves data entered in the instrument form via their browser. The script should be stored as an executable file in the project/instruments/ directory, and the filename must be called Instrument_name.score.
It can be coded in any scripting language but we suggest using our PHP example below. CommentID is passed as the first argument, after which it selects from Instrument_table, performs calculations and updates using the CommentID. To test your scoring script, run it from the tools directory and provide CommentID. Below is a sample scoring script for BMI calculation - this file can be copied from the docs/instruments/ directory:
#!/usr/bin/php
<?php
/* Test_name Scoring
* Description of the scoring algorithm
* @category Instrument
* @package Test_name
* @author Author
* @license Loris License */
require_once "../tools/generic_includes.php";
require_once "Database.class.inc";
$CommentID = $argv[1];
$db =& Database::singleton();
$query = "SELECT * from 'test_name' WHERE CommentID = :CommentID";
$WhereCriteria = array('CommentID'=>$CommentID);
$result = $db->pselectRow($query, $WhereCriteria);
$scores = array();
//check unit of measurement
if ($result['unit_of_measurement'] == 'standard') {
$query_std = "SELECT bmi_value FROM bmi_standard WHERE height_feet =:hgt_feet AND height_inches=:hgt_inches AND weight=:wgt_pounds";
$Where = array('hgt_feet'=>$result['height_feet'], 'hgt_inches'=>$result['height_inches'],
'wgt_pounds'=>$result['weight_pound']);
$scores['bmi_value'] = $db->pselectOne($query_std, $Where);
} else if ($result['unit_of_measurement'] == metric) {$query_metric = "SELECT bmi_value FROM bmi_metric WHERE height_cms=:hgt_cms'' AND weight_kgs=:wgt_kgs";
$Where = array('hgt_cms'=>$result['height_cms'], 'hgt_kgs'=>$result['weight_kgs']);
$scores['bmi_value'] = $db->pselectOne($query_metric, $Where);}
if ($bmi_value <= 18.5) { $scores['bmi_category'] = 'Underweight';}
else if ($bmi_value > 18.5 && $bmi_value <= 24.9 ) {$scores['bmi_category'] = 'Normal weight';}
else if ($bmi_value >= 25 && $bmi_value <= 29.9) {$scores['bmi_category’] = 'Overweight';}
else if ($bmi_value >= 30) {$scores['bmi_category'] = 'Obesity';}
//save scores
$result = $db->update('test_name', $scores, $WhereCriteria);
?>For all *.linst instruments created via the Instrument Builder, sourcing the *.sql file takes care of this step.
All instruments must appear in the test_names and test_subgroups tables. Test Subgroups are used to group/categorize instruments within a timepoint's list of instruments.
For multi-page instruments requiring entries in the instrument_subtests table, or complex instruments that require manual PHP coding, please consult the Loris Instrument Coding Guide for this step.
Insert a record to add the instrument to the test battery for any given cohort, study site, and/or visit:
INSERT INTO test_battery (Test_name, AgeMinDays, AgeMaxDays, Active, Stage, SubprojectID, Visit_label, CenterID, firstVisit, instr_order) VALUES ('$test', '1', '99999', 'Y', 'Visit', '1', 'V1', NULL, NULL, 1);
- Each instrument must have (minimum) one entry for every relevant Subproject (cohort)
- CenterID should be set to NULL if a test is administered across all sites.
** Note that the DCC (Data Coordinating Centre) has CenterID=1 and can thus be used to define a 'dummy' battery for testing out instrument forms on dummy candidate/session records. - VisitLabel should likewise be NULL if an instrument is administered at all visits
- firstVisit is NULL by default; Specify firstVisit='Y' if a particular instrument should always be part of all candidates' first registered visit, or firstVisit='N' if this form should never be part of any candidate's first visit. Note that this column overrides the visit_label entry even if the latter is not null.
- The instr_order column allows for an ordering of the instruments within a battery. Note that, if any value of that column is NULL in the database, the remaining values will no longer be taken into consideration and the ordering of the tests will be as it shows in the table.
If you are modifying your test battery or an instrument form, you may wish to populate this instrument for timepoints for which data entry is already in progress.
To add an instrument form to a timepoint whose visit stage has already been started, run either assign_missing_instruments.php or fix_timepoint_date.php -- located in the tools/ directory.
Depending on the use case, either of these scripts will add the instrument to any relevant timepoints according to the contents of the test_battery table.
Populate examiners table with all personnel likely to administer any questionnaires/tests for each study site. This is a pre-requisite to beginning instrument data entry, as data forms will not save without selecting an examiner.
Register a DCC candidate, then create a timepoint, then start its visit stage (date must be within test_battery-defined age range), then enter sample data, testing each field's type and logic constraints.
A front-end user can only create candidates and visits for the site they belong to. Superusers can change a user's site (including their own) under the User Accounts module.
For Loris 16.0 and prior: For sandbox debugging purposes, ensure the following section appears in config.xml, and toggle to show (1) or hide (0) MySQL queries in the browser. This feature may interfere with JavaScript running in the page, and is not recommended for use in production instances.
<gui>
<showDatabaseQueries>0</showDatabaseQueries>
</gui>Double Data Entry (DDE) is the practice of requiring users to manually input the same dataset twice in order to reduce the risk of error in data entry. For DDE-designated instruments, a participant's instrument data collection at a given visit cannot be finalized in LORIS unless both the first data entry form and second (double) data entry form are completed.
To enable an instrument for double data entry, in the Configuration module inside the Study panel, use the "Double data entry instruments" section to add instrument names. Be very careful when removing an instrument name from this list, regarding the impact on the integrity of the entire dataset.
Note: by default, all forms will have a Double Data Entry (DDE) duplicate form created in the back end (flag table and instrument table) when the instrument is populated for a session. However the DDE form link does not appear in the front end and Double Data Entry completion is not enforced unless the instrument is specified as a Double Data Entry instrument via the Configuration module.
Data entry conflicts detected through between the first and second (double) data entry forms are resolved through the Conflict Resolver
To exclude instruments from the Data Dictionary and Data Query Tool, go to the Configuration module under the "Study" section under "Excluded instruments" and add/select a valid Test Name (e.g. MRI Parameter Form).
Access to specific instruments can be controlled by custom permissions, via the back-end file project/config.xml
<instrumentPermissions>
<!-- By default (false) anyone has permission -->
<useInstrumentPermissions>false</useInstrumentPermissions>
<!-- Add one <instrument> tag for each instrument that is
having its permissions configured. If an instrument
is missing, the default is for users to have access -->
<instrument>
<!-- Instrument name -->
<Test_name>sampleInstrument</Test_name>
<!-- Permission required for accessing the instrument.
If multiple permissions are added, *any* of them individually
will allow access to the instrument -->
<permission>sampleInstrumentPermissionName</permission>
</instrument>
<instrument>
<Test_name>sampleInstrument2</Test_name>
<permission>sampleInstrument2PermissionName</permission>
</instrument>
</instrumentPermissions>The Instrument Manager module is designed allow the Loris database Admin superuser to upload and install instrument forms (*.linst files), and to monitor instrument status in LORIS.
To enable upload and installation of *.linst instrument files created using the Instrument Builder:
i. Create a separate MySQL user account with CREATE_TABLE as well as Select,Insert,Update and Delete privileges on the database. This credential should be stored in project/config.xml within the tag section as quatUser and quatPassword :
<database>
...
<quatUser>%USERNAME%</quatUser>
<quatPassword>%PASSWORD%</quatPassword>
...
</database>ii. Ensure that both project/instruments/ and project/tables_sql/ directories are writable by Apache